ICRC-123: ledger blocks for recording management actions -- freezing and unfreezing of accounts and principals #134

bogwar · 2025-04-01T08:51:23Z

Real World Asset ledgers require several management APIs that would allow authorised entities to carry out ledger changes. This standard introduces four new blocktypes:

block type 123freezeaccount that records that a specific account was frozen by an authorised party
block type 123unfreezeaccount that records that a specific account was unfrozen by an authorised party
block type 123freezeprincipal that records that all of the accounts of a specific principal were frozen by an authorised party
block type 123unfreezeprincipal that records that all of the accounts of a specific principal were unfrozen by an authorised party

Copilot

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

ICRCs/ICRC-123/ICRC-123.md:3

[nitpick] Consider rewording to 'account freezing and unfreezing events' for clarity and consistency.

ICRC-123 introduces new block types for recording account and unfreezing events in ICRC-compliant ledgers.

ICRCs/ICRC-123/ICRC-123.md

Copilot

Copilot reviewed 1 out of 1 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (1)

ICRCs/ICRC-123/ICRC-123.md:3

[nitpick] Consider rephrasing 'recording account and unfreezing events' to 'recording account freeze and unfreeze events' for clarity and consistency with the rest of the document.

ICRC-123 introduces new block types for recording account and unfreezing events in ICRC-compliant ledgers.

ICRCs/ICRC-123/ICRC-123.md

mbjorkqvist · 2025-04-08T08:22:05Z

ICRCs/ICRC-123/ICRC-123.md

+
+### Ledger Enforcement Rules
+
+- A ledger **MUST reject** any transfer transaction (`icrc1_transfer` or `icrc2_transfer_from`) where the **sender or recipient account is currently RESTRICTED**.


What about the spender of an icrc2_transfer_from transaction?

Can/should we say anything about the errors that should be returned in this case? TransferError in ICRC-1 and TransferFromError in ICRC-2 don't seem to specify any variants that would be a good fit here - can we recommend some specific GenericError error code and/or message?

For the first question: thanks for bringing it up. The current version should preclude it.

For the second: I wouldn't introduce a code right now but a reasonable message ("Sending account/receiving account is frozen") may be good. Open to suggestions.

…make approvals

ICRCs/ICRC-123/ICRC-123.md

marc0olo · 2025-05-22T15:55:10Z

ICRCs/ICRC-123/ICRC-123.md

+
+### Querying Freeze Status
+
+Ledgers implementing this standard SHOULD expose a query interface (e.g., `is_account_restricted(account): bool`) that returns whether an account is currently RESTRICTED according to the rules defined in "Account Status". This serves as a convenience layer and does not replace auditing based on block history.


shouldn't we clearly define the query interface to be used? what's the benefit of leaving this up to the implementer?

I think the ecosystem would benefit of having query interfaces clearly defined.

I mean we could leave it up to the implementer to decide whether to expose such function or not. but if they decide to implement it, it would be good to have a common/reusable function name for that.

clients might need to implement some error handling though if this function is not present. (or we add an additional query function to check whether this is function is available or not 🤣 )

this choice is in line with the idea that in this standard we only define the block formats and a standarised interface can then go into a second standard

in any way it would be good to be consistent on this matter also for ICRC-124 where querying the ledger status is not mentioned specifically at this point.

maybe we should mention again that the interface definition is just a suggestion and might be standardized in another ICRC

marc0olo · 2025-05-22T15:55:57Z

ICRCs/ICRC-123/ICRC-123.md

+vec {
+    // ... other supported types like ICRC-1 ...
+    variant { Record = vec {
+        record { "btype"; variant { Text = "123freezeaccount" }};
+        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md)" }}; // Placeholder URL
+    }};
+    variant { Record = vec {
+        record { "btype"; variant { Text = "123unfreezeaccount" }};
+        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md)" }}; // Placeholder URL
+    }};
+    variant { Record = vec {
+        record { "btype"; variant { Text = "123freezeprincipal" }};
+        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md)" }}; // Placeholder URL
+    }};
+    variant { Record = vec {
+        record { "btype"; variant { Text = "123unfreezeprincipal" }};
+        record { "url"; variant { Text = "[https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md](https://github.com/dfinity/ICRC/blob/main/ICRCs/ICRC-123.md)" }}; // Placeholder URL
+    }};
+}


remove placeholder URL comment and check the url content (currently a markdown link)

marc0olo

left some comments

tmu0 · 2025-06-16T12:45:31Z

ICRCs/ICRC-123/ICRC-123.md

+
+This "latest-action-wins" rule implies:
+- A freeze of an account (`123freezeaccount`) can be lifted by a later unfreeze of the same account (`123unfreezeaccount`) or by a later unfreeze of the owning principal (`123unfreezeprincipal`).
+- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts.


Suggested change

- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts.

- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts. Furthermore a freeze of specific accounts of this principal can be lifted by a later `123unfreezeaccount`.

tmu0 · 2025-06-16T12:47:18Z

ICRCs/ICRC-123/ICRC-123.md

+- A freeze of an account (`123freezeaccount`) can be lifted by a later unfreeze of the same account (`123unfreezeaccount`) or by a later unfreeze of the owning principal (`123unfreezeprincipal`).
+- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts.
+
+### Ledger Enforcement Rules


Rules for ICRC122 methods are missing

tmu0 · 2025-06-16T12:56:51Z

ICRCs/ICRC-123/ICRC-123.md

+    - A ledger **MUST reject** any `icrc1_transfer` or `icrc2_transfer_from` transaction where the **sender** account (the `from` account in the operation) is currently RESTRICTED.
+    - The ledger **MAY**, according to its policy, also reject `icrc1_transfer` or `icrc2_transfer_from` transactions if the **recipient** account (the `to` account in the operation) is RESTRICTED, or it MAY allow incoming funds to a RESTRICTED recipient.
+- **ICRC-2 Operations:**
+    - **`icrc2_approve` (Granting Approval):** If an account is RESTRICTED, its owner **MUST NOT** be able to authorize an `icrc2_approve` transaction where this restricted account is the one granting the approval (i.e., the `account` argument in `icrc2_approve` which specifies the owner of the funds being approved for spending).


Suggested change

- **`icrc2_approve` (Granting Approval):** If an account is RESTRICTED, its owner **MUST NOT** be able to authorize an `icrc2_approve` transaction where this restricted account is the one granting the approval (i.e., the `account` argument in `icrc2_approve` which specifies the owner of the funds being approved for spending).

- **`icrc2_approve` (Granting Approval):** If an account is RESTRICTED, its owner **MUST NOT** be able to authorize an `icrc2_approve` transaction where this restricted account is the one granting the approval (i.e., the `caller` in combination with the `from_subaccount` argument in `icrc2_approve` which together specify the `from` account that is being approved for spending).

bogwar added 6 commits March 12, 2025 11:49

initial dir and file for ICRC-123 freeze/unfreeze account

874e51d

draft block format

8595bd5

version with freeze/unfreeze principal

1775f50

semantics section

4b827cf

added a tx record to the blocks

8c18497

wording

49fec16

bogwar changed the title ~~Bw/icrc 123~~ ICRC-123: A standard for recording freezing and unfreezing of accounts and principals in ICRC ledgers Apr 2, 2025

bogwar changed the title ~~ICRC-123: A standard for recording freezing and unfreezing of accounts and principals in ICRC ledgers~~ ICRC-123: ledger blocks for recording management actions -- freezing and unfreezing of accounts and principals Apr 4, 2025

bogwar added 2 commits April 4, 2025 16:14

consistency

c706c1a

consistency

44811ff

bogwar requested a review from Copilot April 7, 2025 12:13

Copilot AI reviewed Apr 7, 2025

View reviewed changes

ICRCs/ICRC-123/ICRC-123.md Outdated Show resolved Hide resolved

removed a duplicate

0351ee9

bogwar requested a review from Copilot April 7, 2025 13:59

Copilot AI reviewed Apr 7, 2025

View reviewed changes

mbjorkqvist reviewed Apr 8, 2025

View reviewed changes

bogwar and others added 10 commits April 11, 2025 13:33

examples wip

ea92373

cleaned up examples

891e5e8

version consistent in terminology and structure with icrc-122

6c5cfb3

Merge branch 'bw/icrc-123' of github.com:dfinity/ICRC into bw/icrc-123

cfdc3ac

conflicts

3d3bb35

cleanup

e0fa18a

fix conflict

8081f7a

conflict

ff9c213

added caller to the tx, and clarified that a frozen principal cannot …

13b64a9

…make approvals

fix examples

6b954f9

marc0olo reviewed May 22, 2025

View reviewed changes

ICRCs/ICRC-123/ICRC-123.md Outdated Show resolved Hide resolved

marc0olo reviewed May 22, 2025

View reviewed changes

tmu0 reviewed Jun 16, 2025

View reviewed changes

bogwar added 2 commits September 12, 2025 12:29

alignment with the new icrc-3

9b525cf

clarify it's blocks that are standardised

f539783


		### Ledger Enforcement Rules

		- A ledger MUST reject any transfer transaction (`icrc1_transfer` or `icrc2_transfer_from`) where the sender or recipient account is currently RESTRICTED.


		### Querying Freeze Status

		Ledgers implementing this standard SHOULD expose a query interface (e.g., `is_account_restricted(account): bool`) that returns whether an account is currently RESTRICTED according to the rules defined in "Account Status". This serves as a convenience layer and does not replace auditing based on block history.

	- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts.
	- A freeze of a principal (`123freezeprincipal`) can be lifted by a later unfreeze of that principal (`123unfreezeprincipal`). It also implicitly unfreezes all accounts owned by that principal unless a more recent, specific `123freezeaccount` block targets one of those accounts. Furthermore a freeze of specific accounts of this principal can be lifted by a later `123unfreezeaccount`.

	- `icrc2_approve` (Granting Approval): If an account is RESTRICTED, its owner MUST NOT be able to authorize an `icrc2_approve` transaction where this restricted account is the one granting the approval (i.e., the `account` argument in `icrc2_approve` which specifies the owner of the funds being approved for spending).
	- `icrc2_approve` (Granting Approval): If an account is RESTRICTED, its owner MUST NOT be able to authorize an `icrc2_approve` transaction where this restricted account is the one granting the approval (i.e., the `caller` in combination with the `from_subaccount` argument in `icrc2_approve` which together specify the `from` account that is being approved for spending).

ICRC-123: ledger blocks for recording management actions -- freezing and unfreezing of accounts and principals #134

Are you sure you want to change the base?

ICRC-123: ledger blocks for recording management actions -- freezing and unfreezing of accounts and principals #134

Uh oh!

Conversation

bogwar commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marc0olo May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marc0olo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bogwar commented Apr 1, 2025 •

edited

Loading

marc0olo May 22, 2025 •

edited

Loading

marc0olo left a comment •

edited

Loading